HTML Extension Files

Query Execution Parameters
Query Result Pages
Syntax
Record Numbers and Counts
Parameters from Internet Data Query files
Navigating Between Pages in Query Results
Variables Affecting the Formatting of Results
HTTP Variables
Error Pages

HTML extension (.htx) files for Microsoft Index Server are very similar to HTML extension files for the Internet Database Connector. There are some differences; this page explains the features of Index Server extension files and the keywords contained in those files..

Note All path names to .htx files must be either full virtual paths or full physical paths with no “.” or “..” components.This applies to .htx files referenced in CiTemplate or as include files.

Do not put these files on a virtual root pointing to a remote Uniform Naming Convention (UNC) share.

Query Execution Parameters

A number of situations leading to unexpected query results are flagged by using built-in variables available in the .htx file. Most .htx pages should include a <%if...%> test on these variables.

CiOutOfDate will be set to the value 1 if the content index has files to filter, or scans to complete. Missing results are possible, because information about particular documents is either from an old version of the document or missing. When this variable is set, it is possible to get results including deleted files, and files whose current version does not match the query.

CiQueryTimedOut will be set to the value 1 when the amount of CPU time spent executing the query exceeds the limit specified in the registry. The variable will be valid for all pages in the result for nonsequentially executed queries. For sequentially executed queries, the CiQueryTimedOut variable is valid only after all available results for the query have been displayed.

CiQueryIncomplete will be set to the value 1 if some portion of the query restriction was ignored. This can occur when a query is forced to use the content index.

Query Result Pages

Query results are split into pages based upon the parameter CiMaxRecordsPerPage. The total number of query result records is governed by the parameter CiMaxRecordsInResultSet. The current page number in the result set is given in the variable CiCurrentPageNumber. For a nonsequential query, the CiTotalNumberPages variable gives the total number of pages in the result and CiRecordsNexPage gives the number of records on the next page. The variables CiContainsFirstRecord and CiContainsLastRecord indicate whether the current page is the first or last in the result set. For an example of how to navigate between pages See Navigating Between Pages in Query Results, later on this page.

Syntax

This section discusses the syntax in .htx files.

<%begindetail%>, <%enddetail%>

The <%begindetail%> and <%enddetail%> tags surround a section of the HTML extension file in which the results of the search will be merged. The section will be interpreted once for each record matching the query on the page. Within the section, the column names delimited with <% and %> are used to mark the position of the returned data from the query. There can be only one detail section in the HTML extension file.

For example:

<dl>
<%begindetail%><p>
<dt>
<%CiCurrentRecordNumber%>.
<b><a href="<%EscapeURL vpath%>"><%filename%></a></b>
<dd>
<b><i>Abscract: </i></b><%characterization%><br>
<font size=-1> - size <%size%> bytes - <%write%> GMT</font>
<%enddetail%></dl>

This query shows the name of the file where the search stringcomes from, gives a brief absract of the file, shows the size of the file in bytes, and shows when the file was last modified.

Note If there are no records returned from the query, the <%begindetail%> section will be skipped.

<%if%>..<%else%>..<%endif%>

HTML extension files can contain conditional logic with an if-then-else statement to control how the Web page is constructed. For example, one common usage is to insert a condition to display a header for the query on the first row within a <% begindetail %> section; but if there are no records returned by the query, to display the text “Sorry, no authors had YTD sales greater than” %sales%. By using the <%if%> statement and a built-in variable called CiLastRecordNumber you can tailor the output so that the error message is printed when no records are returned. Here is an example showing the use of the <%if %> statement.

    <%begindetail%> 
      <%if CiCurrentRecordNumber EQ 1 %> 
        Query results:
        <B>Author YTD Sales<BR></B>
      <%endif%> 
      <%au_lname%>$<%ytd_sales%> 
    <%enddetail%> 
    <P>
    <%if CiLastRecordNumber EQ 0 %> 
      <I><B>Sorry, no authors had YTD sales greater than </I><%sales%>.</B>
      <P>
    <%else%>  
    <HR>
      <I>
      The Web page you see here was created by merging the results
      of the Content query with the template file Sample.htx.
      <P>
      The merge was done by the Microsoft Index Server and
      the results were returned to this Web browser by the Microsoft
      Internet Information Server.
      </I>
    <%endif%> 
    </BODY>
    </HTML>

The general syntax is:

    <%if condition %> 
    HTML text
    [ <%else%> 
      HTML text ]
    <%endif%>

where condition is of the form: value1 operator value2 and operator can be one of the following:

EQ

if value1 equals value2

NE

if value1 does not equal value2

LT

if value1 is less than value2

LE

if value1 is less than or equal to value2

GT

if value1 is greater than value2

GE

if value1 is greater than or equal to value2

CONTAINS

if any part of value1 contains the string value2

ISTYPEEQ
allows the .htx file to determine the VT_TYPE of a particular variable.
value1 IsTypeEq value2
value1 IsTypeEq const1
const1 IsTypeEq value1 
For example, if a variable is of type currency (VT_CY) its type is 6. Type numbers are defined in the OLE specification. A valid .htx comparison would be:
<%if propName IsTypeEq 5 %>Variable is of type currency
<%else%>Variable is NOT type currency
<%endif%> 

This operator is especially useful to check for type VT_EMPTY, an empty property.

ISEMPTY

TRUE if value1 is of type VT_EMPTY, or of type VT_NULL, or is of a textual type (VT_LPSTR, VT_LPWSTR, VT_BSTR, or vectors of the preceding types) and contains only “empty” characters (space, tab, and so on.)

The operands value1 and value2 can be column names, one of the built-in variables, an HTTP variable name (see HTTP Variables later on this page), or a constant. When used in an <%if%> statement, values are not delimited with <% and %> . For example, to do special processing on author name “Green,” use the condition:

    <FORM ACTION="<%HTTP_SCRIPT_NAME%>?" METHOD="POST">
      <%if au_lname EQ "Green"%> 
        this guy is green!
      <%endif%> 
    <%enddetail%>

The <%if%> statement can also be used to do special processing based on information from HTTP variables. For example, to format a page differently based on the type of client Web browser you could include the following in the HTML extension file.

    <%if HTTP_USER_AGENT contains "Mozilla"%> 
      client supports advanced HTML features
    <%else%> 
      client is <%HTTP_USER_AGENT%> 
    <%endif%>

Property types VT_FILETIME and VT_DATE can be compared within <%if%> statements. Use the following format:

<%if fileTime eq "yyyy/mm/dd hh:mm:ss:iii" %>FIle times are identical
<%endif%>

The time must be enclosed in quotes. The year must be a four-digit number (for example, 1996, not 96), and slashes and colons are required.

yyyy = year
mm = month ( 1=January, 12=December, and so on)
dd = day of month ( 1 - 31)
hh = hour of the day in 24-hour format (optional)
mm = minutes (optional)
ss = seconds (optional)
iii = milliseconds (optional)

For example:

<%if write eq "1996/07/21 17:22:11:333" %>File times are identical
<%endif%>

<%EscapeHTML%>, <%EscapeURL%>, <%EscapeRAW %>

The <%EscapeHTML%>, <%EscapeURL%>, and <%EscapeRAW%> keywords can be used to affect the formatting of output strings. These are typically used with variables such as CiRestriction, or CiScope when used in a form or in an anchor.

The output of variables is normally suitable for HTML format. The preceding keywords affect the output format so that the variable can be used correctly in different contexts. The form of the construct is:

<%EscapeHTML variable%>     or
<%EscapeURL variable%>      or
<%EscapeRAW variable%>

where variable is any parameter or variable that could be used in the HTTP Extension file. Constant values can also be used, as in, <%EscapeURL /scripts/query.idq%>.

<%EscapeHTML%> (the default formatting) is used to escape characters that are meaningful in HTML. For example, the symbol > will appear as >.

<%EscapeURL%> is used to do standard escaping for strings that will be URLs (as in the HREF tag of an anchor). For example, the string @size > 10000; will appear as %40size+%3E+10000.

<%EscapeRAW%> is used when no escaping should be done. This might be the case for a variable that is being used as the value of a form variable, or to have the value of a variable that contains HTML code to be interpreted correctly.

File Inclusion

The <%include%> keyword can be used to interpolate the contents of a file into the HTTP Extension page. The syntax of the construct is

<%include filename%>

where filename is the name of the file to be included. The file is named with a full virtual path name, and HTTP Extension constructs are interpreted if found in the file. File includes can be nested, cannot exceed 31 include files total..

Record Numbers and Counts

The CiCurrentRecordNumber built-in variable contains the record number of the current record (1-based). The record number starts at [(page-number - 1) * records-per-page] + 1 for any page. Each time through the <%begindetail%> section, the value of CiCurrentRecordNumber increases by one.

The CiMatchedRecordCount built-in variable contains the value of the total number of records matched in the query (limited to CiMaxRecordsInResultSet). The CiRecordsNextPage built-in variable contains the number of records that will appear on the next page. Referring to either CiMatchedRecordCount or CiRecordsNextPage will cause the query to be nonsequential.

Parameters from Internet Data Query files

A number of predefined parameters are supplied, which can be set in the Internet Data Query files. See Variables in .htx and .idq Files.

In addition, any CGI variable, form parameter, or variable defined in the .idq file can be referred to in the HTTP Extension file by enclosing the variable name in <% and %>. If a variable is referred to that has not been assigned a value, it will result in a null string being sent to the output.

Navigating Between Pages in Query Results

The first record on a page is identified in the variable CiBookmark, which can be used in a form to get to the next page or the previous page. The form variable CiBookmarkSkipCount should be used with CiBookmark to specify the relative offset from the current page. CiBookmarkSkipCount is typically set to either <%CiMaxRecordsPerPage %> or -<%CiMaxRecordsPerPage%>, although it could be set to other multiples of CiMaxRecordsPerPage.

Here is an example of a form that will skip to the next page for a sequential query follows:

     <FORM ACTION="<%HTTP_SCRIPT_NAME%>?" METHOD="POST">
      <INPUT TYPE="HIDDEN"
             NAME="CiBookmark"
             VALUE="<%CiBookmark%>" >
      <INPUT TYPE="HIDDEN"
             NAME="CiBookmarkSkipCount"
             VALUE="<%CiMaxRecordsPerPage%>" >
      <INPUT TYPE="HIDDEN"
             NAME="CiMaxRecordsPerPage"
             VALUE="<%CiMaxRecordsPerPage%>" >
      <INPUT TYPE="HIDDEN"
             NAME="CiRestriction"
             VALUE="<%CiRestriction%>" >
      <INPUT TYPE="HIDDEN"
             NAME="CiScope"
             VALUE="<%CiScope%>" >
      <INPUT TYPE="SUBMIT" VALUE="Next page">
    </FORM>

The following example shows how the buttons for going to adjacent pages can be generated conditionally depending upon the variables CiContainsFirstPage and CiContainsLastPage. It also shows how the number of hits on the next page can be displayed for a nonsequential query.

    <TABLE> <TR>
    <TD> <%if CiContainsFirstRecord eq 0%>  
     <FORM ACTION="<%HTTP_SCRIPT_NAME%>?" METHOD="POST">
        <INPUT TYPE="HIDDEN"
               NAME="CiBookmark"
               VALUE="<%CiBookmark%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiBookmarkSkipCount"
               VALUE="-<%CiMaxRecordsPerPage%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiMaxRecordsPerPage"
               VALUE="<%CiMaxRecordsPerPage%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiRestriction"
               VALUE="<%CiRestriction%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiScope"
               VALUE="<%CiScope%>" >
        <INPUT TYPE="SUBMIT" VALUE="Previous <%CiMaxRecordsPerPage%> Hits">
      </FORM>
    <%endif%> </TD>

    <TD> <%if CiContainsLastRecord eq 0%>  
     <FORM ACTION="<%HTTP_SCRIPT_NAME%>?" METHOD="POST">
        <INPUT TYPE="HIDDEN"
               NAME="CiBookmark"
               VALUE="<%CiBookmark%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiBookmarkSkipCount"
               VALUE="<%CiMaxRecordsPerPage%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiMaxRecordsPerPage"
               VALUE="<%CiMaxRecordsPerPage%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiRestriction"
               VALUE="<%CiRestriction%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiScope"
               VALUE="<%CiScope%>" >
        <INPUT TYPE="SUBMIT" VALUE="Next <%CiRecordsOnNextPage%> Hits">
      </FORM>
    <%endif%> </TD>
    </TR> </TABLE>

Variables Affecting the Formatting of Results

Some variables that can be set in the .idq file affect the formatting of data in the .htx file. The variable CiLocale may be set to affect the formatting of dates, times, currency values, and floating point numbers according to NLS conventions. If CiLocale is not set, the locale is set from the client's browser or the server's default locale, in order of priority.

To change the formatting of datatypes, modify settings in the Regional Settings in the Windows NT Control Panel.

A set of variables taken from the .idq file will be used to enclose and separate elements of column values that are vectors. Unlike all other variables set in the .idq file, these variables cannot be referred to explicitly in the .htx file.

HTTP Variables

Several variables in HTML extension files can give a lot of information about the environment and Web client connected to the server. In addition, all headers sent by the client are available. For Index Server to access these headers, you must convert them:

Add HTTP_ to the beginning
Convert all dashes to underscores.
Convert all letters to uppercase.

The following list gives a listing of default variables.

ALL_HTTP: All HTTP headers that were not already parsed into one of the listed variables. These variables are of the form HTTP_header field name with successive variables separated by a newline character, for example:

HTTP_ACCEPT: */*, q=0.300, audio/x-aiff, audio/basic, image/jpeg, image/gif, text/plain, text/html
HTTP_USER_AGENT: Microsoft Internet Explorer/0.1 (Win32)
HTTP_REFERER: http://webserver/samples/dbsamp/dbsamp3.htm
HTTP_CONTENT_TYPE: application/x-www-form-urlenPRE: 10
HTTP_EXTENSION: Security/Digest

AUTH_TYPE: The type of authorization in use. If the user name has been authenticated by the server, this will contain Basic. Otherwise, it will not be present.
CONTENT_LENGTH: The number of bytes that the script can expect to receive from the client.
CONTENT_TYPE: The content type of the information supplied in the body of a POST request.
GATEWAY_INTERFACE: The revision of the CGI (Common Gateway Interface) specification with which this server complies. The current version is CGI/1.1.

HTTP_ACCEPT: Special-case HTTP header. Values of the Accept: fields are concatenated, separated by “, ”; for example, if the following lines are part of the HTTP header: accept: */*; q=0.1 accept: text/html accept: image/jpeg then the HTTP_ACCEPT variable will have a value of: */*; q=0.1, text/html, image/jpeg.
PATH_INFO: Additional path information, as given by the client. This comprises the trailing part of the URL after the script name but before the query string (if any).
PATH_TRANSLATED: This is the value of PATH_INFO, but with any virtual path name expanded into a directory specification.
QUERY_STRING: The information that follows the question mark (?) in the URL that referenced this script.
REMOTE_ADDR: The IP address of the client.
REMOTE_HOST: The hostname of the client.
REMOTE_USER: This contains the user name supplied by the client and authenticated by the server.
REQUEST_METHOD: The HTTP request method.
SCRIPT_NAME: The name of the script program being run.
SERVER_NAME: The server’s hostname (or IP address) as it should appear in self-referencing URLs.
SERVER_PORT: The TCP/IP port on which the request was received.
SERVER_PROTOCOL: The name and version of the information-retrieval protocol relating to this request, usually HTTP/1.0.
SERVER_SOFTWARE: The name and version of the Web server under which the Internet Server Extension is running.

Error Pages

Through settings in the Windows NT registry, it is possible to configure HTTP Extension pages that are displayed in case of errors encountered while executing a search. Any of the following error types can cause an error page to be displayed:

Query error

An error in a query specification (CiRestriction). This is most likely a user error.

Error in HTTP Extension file

An error was found while formatting the HTTP Extension file. This is probably a configuration error.

Error in Internet Data Query file

An error was found in the query parameter file. This is probably a configuration error, although it might also occur due to unexpected data input from a form.

Some other error

An unspecified error occurred.

Error pages have access to some of the variables available to HTTP Extension files. In addition, there is a variable CiErrorMessage, which gives a message describing the error. See the Error Messages page for a list of the possible values of CiErrorMessage.